---
type: integration
title: '@astrojs/vercel'
description: 学习如何使用 @astrojs/vercel 服务端渲染适配器来部署你的 Astro 项目。
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/vercel/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro'

此适配器允许 Astro 将你的[`hybrid` 或 `server` 渲染站点](/zh-cn/basics/rendering-modes/#按需渲染) 部署到[Vercel](https://www.vercel.com/)。

如果你使用 Astro 作为 [`静态` 站点生成器](/zh-cn/basics/rendering-modes/#预渲染)，只有当你使用额外的 Vercel 服务时（例如 [Vercel 网络分析](https://vercel.com/docs/analytics)，[Vercel 图像优化](https://vercel.com/docs/image-optimization)），你才需要这个适配器。否则，你不需要适配器来部署你的 `静态` 站点。

在我们的 [Vercel 部署指南](/zh-cn/guides/deploy/vercel/) 中学习和部署你的 Astro 站点。

## 为什么选择 Astro Vercel

[Vercel](https://www.vercel.com/) 是一个部署平台，它允许你通过直接连接到 GitHub 仓库来托管你的站点。这个适配器增强了 Astro 的构建过程，为通过 Vercel 进行部署做好了准备。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，也可以[手动安装集成](#手动安装)。

在 Astro 项目中使用以下 `asrto add` 命令添加 Vercel 适配器，以启用 SSR。这将安装 `@astrojs/vercel` 并一步到位地对你的 `astro.config.mjs` 文件进行相应的更改。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add vercel
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add vercel
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add vercel
  ```
  </Fragment>
</PackageManagerTabs>

### 手动安装

首先，使用适合你的包管理器，将 `@astrojs/vercel` 适配器添加到你项目的依赖项中：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/vercel
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/vercel
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/vercel
  ```
  </Fragment>
</PackageManagerTabs>

然后，将适配器和你想要的[按需渲染模式](/zh-cn/basics/rendering-modes/#按需渲染)添加到你的 `astro.config.*` 文件中：

```js title="astro.config.mjs" ins={2, 6-7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel(),
});
```

### 选择目标

你可以部署到不同的目标：

* `serverless`：在 [Node.js 函数](https://vercel.com/docs/concepts/functions/serverless-functions)内进行服务端渲染。
* `static`：生成一个遵循 Vercel 输出格式、重定向等的静态网站。

你可以通过改变导入来切换目标：

```js "serverless" "static"
import vercel from '@astrojs/vercel/serverless';
import vercel from '@astrojs/vercel/static';
```

## 用法

<ReadMore>了解更多关于 [将项目部署到 Vercel](/zh-cn/guides/deploy/vercel/) 的信息。</ReadMore>

你可以通过 CLI ( `vercel deploy` ) 或者通过 [Vercel 控制台](https://vercel.com/) 连接到你的新仓库进行部署。或者，你可以在本地创建生产版本构建：

```sh
astro build
vercel deploy --prebuilt
```

## 配置

要配置这个适配器，将一个对象传递给 `astro.config.mjs` 中的 `vercel()` 函数调用：

### `webAnalytics`

**类型：** `VercelWebAnalyticsConfig`<br/>
**适用于：** Serverless, Static<br/>
<Since v="3.8.0" pkg="@astrojs/vercel" />

你可以通过设置 `webAnalytics: { enabled: true }` 来启用 [Vercel Web Analytics](https://vercel.com/docs/concepts/analytics)。这将在所有页面中注入 Vercel 的跟踪脚本。

```js title="astro.config.mjs" ins={8-10}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  }),
});
```

### `imagesConfig`

**类型：** `VercelImageConfig`<br/>
**适用于：** Serverless, Static<br/>
<Since v="3.3.0" pkg="@astrojs/vercel" />

[Vercel 的图片优化 API](https://vercel.com/docs/concepts/image-optimization) 选项。查看 [Vercel 的图片优化配置文档](https://vercel.com/docs/build-output-api/v3/configuration#images)以获取支持的参数的完整列表。

`domains` 和 `remotePatterns` 属性将自动使用 [Astro 对应的 `image` 设置](/zh-cn/reference/configuration-reference/#image-选项) 来填充。

```js title="astro.config.mjs" ins={8-10}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imagesConfig: {
      sizes: [320, 640, 1280],
    },
  }),
});
```

### `imageService`

**类型：** `boolean`<br/>
**适用于：** Serverless, Static<br/>
<Since v="3.3.0" pkg="@astrojs/vercel" />

启用后，在生产中会自动配置并使用由 Vercel Image Optimization API 提供支持的[图像服务](/zh-cn/reference/image-service-reference/) 。在开发中，将使用由 [`devImageService`](#devimageservice) 指定的图像服务。

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imageService: true,
  }),
});
```

```astro title="src/pages/index.astro"
---
import { Image } from 'astro:assets';
import astroLogo from '../assets/logo.png';
---

<!-- 这里的组件 -->
<Image src={astroLogo} alt="My super logo!" />

<!-- 将会被编译成如下 HTML -->
<img
  src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
  alt="My super logo!"
  loading="lazy"
  decoding="async"
  width="..."
  height="..."
/>
```

### `devImageService`

**类型：** `'sharp' | 'squoosh' | string`<br/>
**适用于：** Serverless, Static
<Since v="3.8.0" pkg="@astrojs/vercel" />
**默认值：** `sharp`

当 [imageService](#imageservice) 启用时，允许你在开发中配置使用哪个图像服务。如果你无法在开发机器上安装 Sharp 的依赖项，但使用另一个图像服务（如 Squoosh）可以让你在开发环境中预览图像，这可能很有用。但构建不会受其影响，将始终使用 Vercel 的图像优化。

它也可以设置为任意值，以使用自定义图像服务而不是 Astro 的内置图像服务。

```js title="astro.config.mjs" ins={8-9}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    imageService: true,
    devImageService: 'squoosh',
  }),
});
```

### `isr`

**类型：** <code>boolean |   VercelISRConfig</code><br/>
**适用于：** Serverless
<Since v="7.2.0" pkg="@astrojs/vercel" />
**默认值：** `false`

允许你的项目作为一个 [ISR (增量式静态再生)](https://vercel.com/docs/incremental-static-regeneration) 功能部署，这个功能以首次请求后预渲染页面相同的方式缓存你按需渲染的页面。

要启用此功能，在你的 `astro.config.mjs` 中的 Vercel 适配器配置里将 `isr` 设置为 true：

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    isr: true,
  }),
});
```

请注意，ISR 功能请求不包括搜索参数，这与静态模式下的 [请求](/zh-cn/reference/api-reference/#astrorequest) 类似。

#### ISR 缓存失效

默认情况下，ISR 函数会在你的部署期间进行缓存。你可以通过设置过期时间，或者完全排除特定路由不进行缓存，来进一步控制缓存。

##### 基于时间的失效

你可以通过配置秒为单位的 `expiration` 值来改变缓存路由的时间长度：

```js title="astro.config.mjs" {8-11}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    isr: {
      // 在首次请求时缓存所有页面，并保存 1 天
      expiration: 60 * 60 * 24,
    },
  }),
});
```

##### 从缓存中排除路径

要实现 Vercel 的[草稿模式](https://vercel.com/docs/build-output-api/v3/features#draft-mode)或[按需增量式静态再生 (ISR)](https://vercel.com/docs/build-output-api/v3/features#on-demand-incremental-static-regeneration-isr)，你可以创建一个绕过令牌，并将其连同任何要从缓存中排除的路由一起提供给 `isr` 配置：

```js title="astro.config.mjs" {7-12}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
    output: "server",
    adapter: vercel({
        isr: {
            // 你创建的一个秘密随机字符串。
            bypassToken: "005556d774a8",
            // 总是提供最新内容的路径。
            exclude: [ "/api/invalidate", "/posts/[...slug]" ]
        }
    })
})
```

### `includeFiles`

**类型：** `string[]`<br/>
**适用于：** Serverless

使用此属性来强制将文件与你的函数打包在一起。当你发现缺失文件时，这很有帮助。

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    includeFiles: ['./my-data.json'],
  }),
});
```

### `excludeFiles`

**类型：** `string[]`<br/>
**适用于：** Serverless

使用此属性来从打包过程中排除任何会被包含的文件。

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    excludeFiles: ['./src/some_big_file.jpg'],
  }),
});
```

### `maxDuration`

**类型：** `number`<br/>
**适用于：** Serverless

使用这个属性来延长或限制无服务器函数运行的最长持续时间（以秒为单位），直到超时。请参阅 [Vercel 文档](https://vercel.com/docs/functions/serverless-functions/runtimes#maxduration) 获取你的账号计划的默认和最大时限。

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
// ...
  output: "server",
  adapter: vercel({
    maxDuration: 60
  }),
});
```

### 函数打包配置

Vercel 适配器默认将所有路由组合成一个函数。

你也可以使用 `functionPerRoute` 选项将构建拆分为每个路由一个函数。这样可以减少每个函数的大小，这意味着你不太可能超过单个函数的大小限制。并且，代码启动更快。

在启用 `functionPerRoute` 前请查验你的 Vercel 计划是否包含足够数量的函数。例如，Vercel 的免费计划限制每个部署拥有不超过 12 个函数。如果你的 Vercel 计划不足以满足项目中的路由数量，你将在部署过程中收到错误消息。

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    functionPerRoute: true,
  }),
});
```

### 在 Vercel Edge 函数上运行 Astro 中间件

`@astrojs/vercel/serverless` 适配器可以根据你代码库中的 Astro 中间件创建一个 [边缘函数](https://vercel.com/docs/functions/edge-functions)。当启用 `edgeMiddleware` 时，边缘函数将为包括静态资源、预渲染页面和按需渲染页面在内的所有请求执行你的中间件代码。

对于按需渲染的页面，`context.locals` 对象会被 JSON 序列化并通过标头发送给无服务器函数，由该函数执行渲染。作为安全措施，除非请求来自生成的边缘函数，否则无服务器函数将拒绝服务，并返回 `403 Forbidden` 响应。

这是一个选择性功能。要启用它，请将 `edgeMiddleware` 设置为 `true`：

```js title="astro.config.mjs" "edgeMiddleware: true"
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    edgeMiddleware: true,
  }),
});
```
边缘中间件可以用 `ctx.locals.vercel.edge` 访问 Vercel 的 [`RequestContext`](https://vercel.com/docs/functions/edge-middleware/middleware-api#requestcontext) 。如果你正在使用 TypeScript，可以通过更新 `src/env.d.ts` 来使用 `EdgeLocals` 获得正确的类型定义：

```ts
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />

type EdgeLocals = import('@astrojs/vercel').EdgeLocals

declare namespace App {
  interface Locals extends EdgeLocals {
    // ...
  }
}
```

### Node.js 版本支持
`@astrojs/vercel` 适配器支持特定的 Node.js 版本，用于在 Vercel 上部署 Astro 项目。要在 Vercel 上查看受支持的 Node.js 版本，请单击项目的设置选项卡，然后向下滚动到 “Node.js版本” 部分。

查看[Vercel文档](https://vercel.com/docs/functions/serverless-functions/runtimes/node-js#default-and-available-versions)了解更多信息。

[astro-integration]: /zh-cn/guides/integrations-guide/
